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INTRODUCTION 


Microsoft's new command shell/scripting language. This series 
provides a task-based introduction to Windows PowerShell cmdlets: 
rather than focusing on the individual cmdlets themselves, the emphasis 
is on the tasks you can carry out using those cmdlets. These tasks 


include everything from reading and writing text files to managing 


event logs to sorting and filtering data. 








Applies To: Windows PowerShell 2.0, Windows PowerShell 3.0, 
Windows PowerShell 4.0 


Graphical user interfaces use some basic concepts that are well known 
to most computer users. Users rely on the familiarity of those interfaces 
to accomplish tasks. Operating systems present users with a graphical 
representation of items that can be browsed, usually with drop-down 
menus for accessing specific functionality and context menus for 


accessing context-specific functionality. 


A command-line interface (CLI), such as Windows PowerShell, must 
use a different approach to expose information, because it does not have 
menus or graphical systems to help the user. You need to know 
command names before you can use them. Although you can type 
complex commands that are equivalent to the features in a GUI 
environment, you must become familiar with commonly-used 
commands and command parameters. 
Most CLIs do not have patterns that can help the user to learn the 
interface. Because CLIs were the first operating system shells, many 
command names and parameter names were selected arbitrarily. Terse 
command names were generally chosen over clear ones. Although help 
systems and command design standards are integrated into most CLIs, 
they have been generally designed for compatibility with the earliest 
commands, so the command set is still shaped by decisions made 
decades ago. 
Windows PowerShell was designed to take advantage of a user's 
historic knowledge of CLIs. In this chapter, we will talk about some 
basic tools and concepts that you can use to learn Windows PowerShell 
quickly. They include: 

° Using Get-Command 

. Using Cmd.exe and UNIX commands 

° Using External Commands 

° Using Tab-Completion 

° Using Get-Help 


for example, they mention that using double quotes you can evaluate 


variables inside the strings: 


$x = "hello" 


"$x world" 


results in "hello world" 


but 


$y = “hello","goodbye" 


"$y[0] world" 


does not. So, trial and error commence and we try: 


"${y[0]} world" which also fail. 


It would be a lot better if they bothered to explain exactly how the 
various basic tokens are built up, for example what goes into a script 


block? will for example: 


$x= "hello" 


0..4 | foreach-object -process { "$x world $_" } 


Give the expected result? Yes, it does! 


But for some reason using $args inside foreach does not - because 
presumably foreach-process has it's own arguments which replaces the 
$args variable, probably best then to store the $args into another 


variable and then use it? Yes, that works. 


Things would be a lot easier if they bothered to have a few chapters to 
explain these basic stuff rather than having each of us finding out by 


experimentation. 


Seems they skip immediately to the fun part and drop the tedious basic 


building blocks of the scripting language. 


Also, if they could allow a character to escape the meaning of $ inside 


double quoted strings so you could write stuff like: 


'N$x — '$x'" 


To get the output 


$x = 'Hello' 


but that is not just documentation, that is change of the language. Yes, 


I know you can get the same 


string by doing: 


("$"+ " — '$x'") 


mt 


but it is easier to write "\$x = '$x'" to achieve the same thing. 


About Windows PowerShell 


Discoverability 

Windows PowerShell makes it easy to discover its features. For 
example, to find a list of cmdlets that view and change Windows 
services, type: 

get-command *-service 

After discovering which cmdlet accomplishes a task, you can learn 
more about the cmdlet by using the Get-Help cmdlet. For example, to 
display help about the Get-Service cmdlet, type: 

get-help get-service 

To fully understand the output of that cmdlet, pipe its output to the Get- 
Member cmdlet. For example, the following command displays 
information about the members of the object output by the Get-Service 
cmdlet. 


get-service | get-member 


Consistency 
Managing systems can be a complex endeavor and tools that have a 


consistent interface help to control the inherent complexity. 


Unfortunately, neither command-line tools nor scriptable COM objects 


have been known for their consistency. 


The consistency of Windows PowerShell is one of its primary assets. 
For example, if you learn how to use the Sort-Object cmdlet, you can 
use that knowledge to sort the output of any cmdlet. You do not have to 


learn the different sorting routines of each cmdlet. 


In addition, cmdlet developers do not have to design sorting features for 
their cmdlets. Windows PowerShell gives them a framework that 
provides the basic features and forces them to be consistent about many 
aspects of the interface. The framework eliminates some of the choices 
that are typically left to the developer, but, in return, it makes the 
development of robust and easy-to-use cmdlets much simpler. 
Interactive and Scripting Environments 

Windows PowerShell is a combined interactive and_ scripting 
environment that gives you access to command-line tools and COM 
objects, and also enables you to use the power of the .NET Framework 
Class Library (FCL). 

This environment improves upon the Windows Command Prompt, 
which provides an interactive environment with multiple command-line 
tools. It also improves upon Windows Script Host (WSH) scripts, which 
let you use multiple command-line tools and COM automation objects, 
but do not provide an interactive environment. 

By combining access to all of these features, Windows PowerShell 
extends the ability of the interactive user and the script writer, and 


makes system administration more manageable. 


Object Orientation 


Although you interact with Windows PowerShell by typing commands 
in text, Windows PowerShell is based on objects, not text. The output 
of a command is an object. You can send the output object to another 
command as its input. As a result, Windows PowerShell provides a 


familiar interface to people experienced with other shells, while 


introducing a new and powerful command-line paradigm. It extends the 
concept of sending data between commands by enabling you to send 


objects, rather than text. 


Understanding Important Windows PowerShell Concepts 


Commands Are Not Text-Based 


Unlike traditional command-line interface commands, Windows 
PowerShell cmdlets are designed to deal with objects - structured 
information that is more than just a string of characters appearing on the 
screen. Command output always carries along extra information that 
you can use if you need it. We will discuss this topic in depth in this 
document. 

If you have used text-processing tools to process command-line data in 
the past, you will find that they behave differently if you try to use them 
in Windows PowerShell. In most cases, you do not need text-processing 
tools to extract specific information. You can access portions of the data 
directly by using standard Windows PowerShell object manipulation 


commands. 


The Command Family Is Extensible 

Interfaces such as Cmd.exe do not provide a way for you to directly 
extend the built-in command set. You can create external command-line 
tools that run in Cmd.exe, but these external tools do not have services, 
such as Help integration, and Cmd.exe does not automatically know that 
they are valid commands. 

The native binary commands in Windows PowerShell, known as 
cmdlets (pronounced command-lets), can be augmented by cmdlets that 


you create and that you add to Windows PowerShell by using snap-ins. 


Windows PowerShell snap-ins are compiled, just like binary tools in 
any other interface. You can use them to add Windows PowerShell 
providers to the shell, as well as new cmdlets. 

Because of the special nature of the Windows PowerShell internal 
commands, we will refer to them as cmdlets. 

Note: 

Windows PowerShell can run commands other than cmdlets. We will 
not be discussing them in detail in the Windows PowerShell User's 
Guide, but they are useful to know about as categories of command 
types. Windows PowerShell supports scripts that are analogous to 
UNIX shell scripts and Cmd.exe batch files, but have a .ps1 file name 
extension. Windows PowerShell also allows you to create internal 


functions that can be used directly in the interface or in scripts. 


Windows PowerShell Handles Console Input and Display 

When you type a command, Windows PowerShell always processes the 
command-line input directly. Windows PowerShell also formats the 
output that you see on the screen. This is significant because it reduces 
the work required of each cmdlet and ensures that you can always do 
things the same way regardless of which cmdlet you are using. One 
example of how this simplifies life for both tool developers and users is 
command-line Help. 

Traditional command-line tools have their own schemes for requesting 
and displaying Help. Some command-line tools use /? to trigger the 
Help display; others use -?, /H, or even //. Some will display Help in a 
GUI window, rather than in the console display. Some complex tools, 
such as application updaters, unpack internal files before displaying 
their Help. If you use the wrong parameter, the tool might ignore what 
you typed and begin performing a task automatically. When you enter 
a command in Windows PowerShell, everything you enter is 


automatically parsed and pre-processed by Windows PowerShell. If you 


use the -? parameter with a Windows PowerShell cmdlet, it always 
means "show me Help for this command". Cmdlet developers do not 
have to parse the command; they only need to provide the Help text. 

It is important to understand that the Help features of Windows 
PowerShell are available even when you run traditional command-line 
tools in Windows PowerShell. Windows PowerShell processes the 
parameters and passes the results to the external tools. 

Note: 

If you run angraphic application in Windows PowerShell, the window 
for the application opens. Windows PowerShell intervenes only when 
processing the command-line input you supply or the application output 
returned to the console window; it does not affect how the application 
works internally. 

Windows PowerShell Uses Some C# Syntax 

Windows PowerShell has syntax features and keywords that are very 
similar to those used in the C# programming language, because 
Windows PowerShell is based on the .NET Framework. Learning 
Windows PowerShell will make it much easier to learn C#, if you are 
interested in the language. 

If you are not a C# programmer, this similarity is not important. 
However, if you are already familiar with C#, the similarities can make 


learning Windows PowerShell much easier. 


Easy Transition to Scripting 

Windows PowerShell makes it easy to transition from typing commands 
interactively to creating and running scripts. You can type commands 
at the Windows PowerShell command prompt to discover the 
commands that perform a task. Then, you can save those commands in 


a transcript or a history before copying them to a file for use as a script. 


Understanding Important Windows PowerShell Concepts 


Commands Are Not Text-Based 

Unlike traditional command-line interface commands, Windows 
PowerShell cmdlets are designed to deal with objects - structured 
information that is more than just a string of characters appearing on the 
screen. Command output always carries along extra information that 
you can use if you need it. We will discuss this topic in depth in this 
document. 

If you have used text-processing tools to process command-line data in 
the past, you will find that they behave differently if you try to use them 
in Windows PowerShell. In most cases, you do not need text-processing 
tools to extract specific information. You can access portions of the data 
directly by using standard Windows PowerShell object manipulation 


commands. 


The Command Family Is Extensible 

Interfaces such as Cmd.exe do not provide a way for you to directly 
extend the built-in command set. You can create external command-line 
tools that run in Cmd.exe, but these external tools do not have services, 
such as Help integration, and Cmd.exe does not automatically know that 
they are valid commands. 

The native binary commands in Windows PowerShell, known as 
cmdlets (pronounced command-lets), can be augmented by cmdlets that 
you create and that you add to Windows PowerShell by using snap-ins. 
Windows PowerShell snap-ins are compiled, just like binary tools in 
any other interface. You can use them to add Windows PowerShell 
providers to the shell, as well as new cmdlets. 

Because of the special nature of the Windows PowerShell internal 


commands, we will refer to them as cmdlets. 


Note: 


Windows PowerShell can run commands other than cmdlets. We will 
not be discussing them in detail in the Windows PowerShell User's 
Guide, but they are useful to know about as categories of command 
types. Windows PowerShell supports scripts that are analogous to 
UNIX shell scripts and Cmd.exe batch files, but have a .ps1 file name 
extension. Windows PowerShell also allows you to create internal 


functions that can be used directly in the interface or in scripts. 


Windows PowerShell Handles Console Input and Display 

When you type a command, Windows PowerShell always processes the 
command-line input directly. Windows PowerShell also formats the 
output that you see on the screen. This is significant because it reduces 
the work required of each cmdlet and ensures that you can always do 
things the same way regardless of which cmdlet you are using. One 
example of how this simplifies life for both tool developers and users is 
command-line Help. 

Traditional command-line tools have their own schemes for requesting 
and displaying Help. Some command-line tools use /? to trigger the 
Help display; others use -?, /H, or even //. Some will display Help in a 
GUI window, rather than in the console display. Some complex tools, 
such as application updaters, unpack internal files before displaying 
their Help. If you use the wrong parameter, the tool might ignore what 
you typed and begin performing a task automatically. When you enter 
a command in Windows PowerShell, everything you enter is 
automatically parsed and pre-processed by Windows PowerShell. If you 
use the -? parameter with a Windows PowerShell cmdlet, it always 
means "show me Help for this command". Cmdlet developers do not 
have to parse the command; they only need to provide the Help text. 

It is important to understand that the Help features of Windows 


PowerShell are available even when you run traditional command-line 


tools in Windows PowerShell. Windows PowerShell processes the 


parameters and passes the results to the external tools. 

Note: 

If you run an graphic application in Windows PowerShell, the window 
for the application opens. 

Windows PowerShell intervenes only when processing the command- 
line input you supply or the application output returned to the console 
window; it does not affect how the application works internally. 
Windows PowerShell Uses Some C# Syntax 


Windows PowerShell has syntax features and keywords that are very 
similar to those used in the C# programming language, because 
Windows PowerShell is based on the .NET Framework. Learning 
Windows PowerShell will make it much easier to learn C#, if you are 
interested in the language. 

If you are not a C# programmer, this similarity is not important. 
However, if you are already familiar with C#, the similarities can make 


learning Windows PowerShell much easier. 


Learning Windows PowerShell Names 


Learning names of commands and command parameters is a significant 
time investment with most command-line interfaces. The issue is that 
there are very few patterns, so the only way to learn is by memorizing 
each command and each parameter that you need to use on a regular 
basis. 

When you work with a new command or parameter, you cannot 
generally use what you already know; you have to find and learn a new 
name. If you look at how interfaces grow from a small set of tools with 
incremental additions to functionality, it is easy to see why the structure 
is nonstandard. With command names in particular, this may sound 
logical since each command is a separate tool, but there is a better way 


to handle command names. 


Most commands are built to manage elements of the operating system 
or applications, such as services or processes. The commands have a 
variety of names that may or may not fit into a family. For example, on 
Windows systems, you can use the net start and net stop commands to 
start and stop a service. There is another more generalized service 
control tool for Windows that has a completely different name, sc, that 
does not fit into the naming pattern for the net service commands. For 
process management, Windows has the tasklist command to list 


processes and the taskkill command to kill processes. 


Commands that take parameters have irregular parameter 
specifications. You cannot use the net start command to start a service 
on a remote computer. The sc command will start a service on a remote 
computer, but to specify the remote computer, you must prefix its name 
with a double backslash. For example, to start the spooler service on a 
remote computer named DCO1, you would type sc \\DCO1 start spooler. 
To list tasks running on DCO1, you need to use the /S (for "system") 
parameter and supply the name DCO1 without backslashes, like this: 
tasklist /S DCO1. 


Although there are important technical distinctions between a service 
and a process, they are both examples of manageable elements on a 
computer that have a well-defined life cycle. You may want to start or 
stop a service or process, or get a list of all currently running services 
or processes. In other words, although a service and a process are 
different things, the actions we perform on a service or a process are 
often conceptually the same. Furthermore, choices we may make to 
customize an action by specifying parameters may be conceptually 
similar as well. Windows PowerShell exploits these similarities to 
reduce the number of distinct names you need to know to understand 


and use cmdlets. 
Cmdlets Use Verb-Noun Names to Reduce Command Memorization 


Windows PowerShell uses a "verb-noun" naming system, where each 


cmdlet name consists of a standard verb hyphenated with a specific 


noun. Windows PowerShell verbs are not always English verbs, but 
they express specific actions in Windows PowerShell. Nouns are very 
much like nouns in any language, they describe specific types of objects 
that are important in system administration. It is easy to demonstrate 
how these two-part names reduce learning effort by looking at a few 
examples of verbs and nouns. 

Nouns are less restricted, but they should always describe what a 
command acts upon. Windows PowerShell has commands such as Get- 
Process, Stop-Process, Get-Service, and StopService. 

In the case of two nouns and two verbs, consistency does not simplify 
learning that much. However, if you look at a standard set of 10 verbs 
and 10 nouns, you then have only 20 words to understand, but those 
words can be used to form 100 distinct command names. Frequently, 
you can recognize what a command does by reading its name, and it is 
usually apparent what name should be used for a new command. For 
example, a computer shutdown command might be Stop-Computer. A 
command that lists all computers on a network might be Get-Computer. 
The command that gets the system date is Get-Date. 

You can list all commands that include a particular verb with the -Verb 
parameter for 

GetCommand (We will discuss Get-Command in detail in the next 


section). For example, to see all cmdlets that use the verb Get, type: 


PS> Get-Command -Verb Get 


CommandType Name Definition 
Cmdlet Get-Acl Get-Acl [[-Path] <String[]>]... 
Cmdlet Get-Alias Get-Alias [[-Name] <String[]... 


Cmdlet Get-AuthenticodeSignature Get-AuthenticodeSignature 
[-... Cmdlet Get-ChildItem Get-ChildItem [[-Path] 


<Stri... 


The -Noun parameter is even more useful because it allows you to see 
a family of commands that affect the same type of object. For example, 
if you want to see which commands are available for managing services, 
type following command: 


PS> Get-Command -Noun Service 


CommandType Name Definition 

Cmdlet Get-Service Get-Service [[-Name] <String... 
Cmdlet New-Service New-Service [-Name] <String>... 
Cmdlet Restart-Service Restart-Service [-Name] <Str... 
Cmdlet Resume-Service Resume-Service [-Name] 
<Stri... 

Cmdlet Set-Service Set-Service [-Name] <String>... 
Cmdlet Start-Service Start-Service [-Name] <Strin... 
Cmdlet Stop-Service Stop-Service [-Name] <String... 
Cmdlet Suspend-Service Suspend-Service [-Name] 
<Str... 


A command is not necessarily a cmdlet, just because it has a verb-noun 
naming scheme. One example of a native Windows PowerShell 
command that is not a cmdlet but has a verb-noun name, is the command 
for clearing a console window, Clear-Host. The Clear-Host command 
is actually an internal function, as you can see if you run Get-Command 


against it: 


PS> Get-Command -Name Clear-Host 


CommandType Name Definition 


Function Clear-Host $spaceType = [System.Managem... 


Cmdlets Use Standard Parameters 


As noted earlier, commands used in traditional command-line interfaces 
do not generally have consistent parameter names. Sometimes 
parameters do not have names at all. When they do, they are often 
single-character or abbreviated words that can be typed rapidly but are 
not easily understood by new users. 

Unlike most other traditional command-line interfaces, Windows 
PowerShell processes parameters directly, and it uses this direct access 
to the parameters along with developer guidance to standardize 
parameter names. Although this does not guarantee that every cmdlet 


will always conform to the standards, it does encourage it. 


Note: 

Parameter names always have a '-' prepended to them when you use 
them, to allow Windows PowerShell to clearly identify them as 
parameters. In the Get-Command -Name Clear-Host example, the 


parameter's name is Name, but it is entered as -Name. 


Here are some of the general characteristics of the standard parameter 
names and usages. 

The Help Parameter , 

When you specify the -? parameter to any cmdlet, the cmdlet is not 
executed. Instead, Windows PowerShell displays help for the cmdlet. 
Common Parameters 

Windows PowerShell has several parameters known as common 
parameters. Because these parameters are controlled by the Windows 
PowerShell engine, whenever they are implemented by a cmdlet, they 


will always behave the same way. The common parameters are Whatlf, 


Confirm, Verbose, Debug, Warn, ErrorAction, ErrorVariable, 
OutVariable, and OutBuffer. 

Suggested Parameters 

The Windows PowerShell core cmdlets use standard names for similar 
parameters. Although the use of parameter names is not enforced, there 
is explicit guidance for usage to encourage standardization. 

For example, the guidance recommends naming a parameter that refers 
to a computer by name as ComputerName, rather than Server, Host, 
System, Node, or other common alternative words. Among the 
important suggested parameter names are Force, Exclude, Include, 


PassThru, Path, and CaseSensitive. 


Getting Information About Commands 


The Windows PowerShell Get-Command cmdlet gets all commands 
that are available in your current session. When you type Get-Command 
at a Windows PowerShell prompt, you will see output similar to the 


following: 


PS> Get-Command 


CommandType Name Definition 

Cmdlet Add-Content Add-Content [-Path] <String[... 
Cmdlet Add-History Add-History [[-InputObject] ... 
Cmdlet Add-Member Add-Member [-MemberType] 
<PS... 


This output looks a lot like the Help output of Cmd.exe: a tabular 
summary of internal commands. In the excerpt of the Get-Command 


command output shown above, every command shown has a 


CommandType of Cmdlet. A cmdlet is Windows PowerShell's intrinsic 
command type — a type that corresponds roughly to the dir and cd 
commands of Cmd.exe and to built-ins in UNIX shells such as BASH. 
In the output of the Get-Command command, all the definitions end 
with ellipses (...) to indicate that PowerShell cannot display all the 
content in the available space. When Windows PowerShell displays 
output, it formats the output as text and then arranges it to make the data 
fit cleanly into the window. We will talk about this later in the section 
on formatters. The GetCommand cmdlet has a Syntax parameter that 
gets the syntax of each cmdlet. To get the syntax of the Get-Help 


cmdlet, use the following command: 


Get-Command Get-Help —Syntax 

Get-Help [[-Name] <String>] [-Path <String>] [-Category <String[]>] 
[- Component <String[]>] [-Functionality <String[]>] 

[-Role <String[]>] [-Full] [-Online] [-Verbose] [-Debug] [-ErrorAction 
<ActionPreference>] [-WarningAction <ActionPreference>]  [- 
ErrorVariable 

<String>] [-WarningVariable <String>] [-OutVariable <String>] [- 
OutBuffer <Int32>] 


Get-Help [[-Name] <String>] [-Path <String>] [-Category <String[]>] 
2 

Component <String[]>] [-Functionality <String[]>] 

[-Role <String[]>] [-Detailed] [-Online] [-Verbose] [-Debug] [- 
ErrorAction 

<ActionPreference>] [-WarningAction <ActionPreference>]  [- 
ErrorVariable 

<String>] [-WarningVariable <String>] [-OutVariable <String>] [- 
OutBuffer <Int32>] 


Get-Help [[-Name] <String>] [-Path <String>] [-Category <String[]>] 
ie 

Component <String[]>] [-Functionality <String[]>] 

[-Role <String[]>] [-Examples] [-Online] [-Verbose] [-Debug] [- 
ErrorAction 

<ActionPreference>] [-WarningAction <ActionPreference>]  [- 
ErrorVariable 

<String>] [-WarningVariable <String>] [-OutVariable <String>] [- 
OutBuffer <Int32>] 


Get-Help [[-Name] <String>] [-Path <String>] [-Category <String[]>] 
[- 

Component <String[]>] [-Functionality <String[]>] 

[-Role <String[]>] [-Parameter <String>] [-Online] [-Verbose] [- 
Debug] {ErrorAction <ActionPreference>] [-WarningAction 
<ActionPreference>|] [- 

ErrorVariable <String>] [-WarningVariable <String>] [-OutVariable 
<String>] [- OutBuffer <Int32>] 


Displaying Available Command Types 

The Get-Command command does not list every command that is 
available in Windows 

PowerShell. Instead, the Get-Command command lists only the cmdlets 
in the current session. Windows PowerShell actually supports several 
other types of commands. Aliases, functions, and scripts are also 
Windows PowerShell commands, although they are not discussed in 
detail in the Windows PowerShell User's Guide. External files that are 
executable, or have a registered file type handler, are also classified as 
commands. 


To get all commands in the session, type: 


Get-Command * 


Because this list includes external files in your search path, it may 
contain thousands of items. It is more useful to look at a reduced set of 
commands. 

To get native commands of other types, use the CommandType 


parameter of the GetCommand cmdlet. 


Note: 

The asterisk (*) is used for wildcard matching in Windows PowerShell 
command arguments. The * means "match one or more of any 
characters". You can type Get-Command a* to find all commands that 
begin with the letter "a". Unlike wildcard matching in Cmd.exe, 


Windows PowerShell's wildcard will also match a period. 


To get command aliases, which are the assigned nicknames of 
commands, type: Get-Command -CommandType Alias To get the 


functions in the current session, type: 
Get-Command -CommandType Function To 
display scripts in Windows PowerShell's search path, type: 


Get-Command -CommandType Script 


Getting Detailed Help Information 


Getting Help for Cmdlets 
To get Help about Windows PowerShell cmdlets, use the Get-Help 
cmdlet. For example, to get Help for the Get-ChildItem cmdlet, type: 


get-help get-childitem or get-childitem -? 


You can even get Help about the Get-Help cmdlet. For example: get- 
help get-help 

To get a list of all the cmdlet Help topics in your session, type: get-help 
-category cmdlet 

To display one page of each Help topic at a time, use the help function 
or its alias man. For example, to display Help for the Get-ChildItem 
cmdlet, type man get-childitem or 

help get-childitem 

To display detailed information about a cmdlet, function, or script, 
including descriptions of its parameters and examples of its use, use the 
Detailed parameter of the Get-Help cmdlet. For example, to get detailed 
information about the Get-ChildItem cmdlet, type: 

get-help get-childitem -detailed 

To display all content in the Help topic, use the Full parameter of the 
Get-Help cmdlet. For example, to display all content in the Help topic 
for the Get-ChildItem cmdlet, type: 

get-help get-childitem -full 

To get detailed Help about the parameters of a cmdlet, use the Parameter 
parameter of the Get-Help cmdlet. For example, to get detailed Help for 
all of the parameters of the GetChildItem cmdlet, type: 

get-help get-childitem -parameter * 

To display only the examples in a Help topic, use the Example 
parameter of the Get-Help. For example, to display only the examples 
in the Help topic for the Get-ChildItem cmdlet, type: get-help get- 
childitem -examples 

For information about how to write Help topics for the cmdlets that you 
write, see the "How to Write Cmdlet Help" topic in MSDN. 

Getting Conceptual Help 

The Get-Help cmdlet also displays information about conceptual topics 
in Windows PowerShell, including topics about the Windows 


" 


PowerShell language. Conceptual Help topics begin with the "about_ 


prefix, such as about_line_editing. (The name of the conceptual topic 
must be entered in English even on non-English versions of Windows 


PowerShell.) To display a list of conceptual topics, type: 

get-help about_* 

To display a particular Help topic, type the topic name, for example: 
get-help about_command_syntax 

The parameters of Get-Help, such as Detailed, Parameter, and 


Examples, have no effect on the display of conceptual Help topics. 


Getting Help About Providers 

The Get-Help cmdlet displays information about Windows PowerShell 
providers. To get Help for a provider, type "Get-Help" followed by the 
provider name. For example, to get Help for the Registry provider, type: 
get-help registry 

To get a list of all the provider Help topics in your session, type get- 
help -category provider 

The parameters of Get-Help, such as Detailed, Parameter, and 


Examples, have no effect on the display of provider Help topics. 


Getting Help About Scripts and Functions 

Many scripts and functions in Windows PowerShell have Help topics. 
Use the Get-Help cmdlet to display the Help topics for scripts and 
functions. 

To display the Help for a function, type "get-help" followed by the 
function name. For example, to get Help for the Disable-PSRemoting 
function, type: 

get-help disable-psremoting 

To display the Help for a script, type the fully qualified path to the script 
file. If the script is in a path that is listed in the Path environment 


variable, you can omit the path from the command. For example, if you 


have a script called "TestScript.ps1" in your C:\PS-Test directory, to 
display the Help topic for the script, type: get-help c:\ps- 
test\TestScript.ps1 

The parameters that were designed for displaying cmdlet Help, such as 
Detailed, Full, Examples, and Parameter, work for script Help and 
function Help, too. However, when you display all Help, by typing "get- 
help *", Help for functions and scripts does not appear. 

For information about writing Help topics for your functions and 
scripts, see about_Functions, about_Scripts, and 


about_Comment_Based_Help. 


Getting Help Online 

If you are connected to the Internet, one of the best ways to get Help is 
to view the Help topics online. Because online topics are easy to update, 
they are likely to provide the most current content. 

To get Help online, try the Online parameter of the Get-Help cmdlet. 
The Online parameter of the Get-Help cmdlet works only for cmdlet 
Help, function Help, and script Help. You cannot use the Online 
parameter with conceptual (About) topics or provider Help topics. Also, 
because this feature is optional, it does not work for every cmdlet, 
function, or script Help topic. 

However, all the Help topics that come with Windows PowerShell, 
including provider Help and conceptual (About) Help topics, are 
available online in the Windows PowerShell section of the Microsoft 
TechNet Library. 

To use the Online parameter of the Get-Help cmdlet, use the following 
command format. gethelp <command-name> -online 

For example, to get the online version of the Help topic about the Get- 
ChildItem cmdlet, type: get-help get-childitem -online 

If an online version of the Help topic is available, it will open in your 


default browser. 


If online Help is supported for a Help topic, you can also view the 
Internet address (URL) of the Help topic. The Internet address appears 
in the Related Links section of a Help topic. For example, to see the 
URL for the online version of the Add-Computer cmdlet, type: get-help 
add-computer 

The first line in the Related Links section of the topic is shown below. 


Online version: http://go.microsoft.com/fwlink/?LinkID=135 194 


Using Familiar Command Names 


Using a mechanism called aliasing, Windows PowerShell allows users 
to refer to commands by alternate names. Aliasing allows users with 
experience in other shells to reuse common command names that they 
already know to perform similar operations in Windows PowerShell. 
Although we will not discuss Windows PowerShell aliases in detail, you 
can still use them as you get started with Windows PowerShell. 
Aliasing associates a command name that you type with another 
command. For example, 

Windows PowerShell has an internal function named Clear-Host that 
clears the output window. If you type either the cls or clear command 
at a command prompt, Windows PowerShell interprets that this is an 
alias for the Clear-Host function and runs the Clear-Host function. This 
feature helps users to learn Windows PowerShell. First, most Cmd.exe 
and UNIX users have a large repertoire of commands that users already 
know by name, and although the Windows PowerShell equivalents may 
not produce identical results, they are close enough in form that users 
can use them to do work without having to first memorize the Windows 
PowerShell names. Second, the major source of frustration in learning 
a new shell when the user is already familiar with another shell, is the 
errors that are caused by "finger memory". If you have used Cmd.exe 


for years, when you have a screen full of output and want to clean it up, 


you would reflexively type the cls command and press the ENTER key. 
Without the alias to the Clear-Host function in Windows PowerShell, 


mt 


you would simply get the error message "'cls' is not recognized as a 
cmdlet, function, operable program, or script file." and be left with no 
idea of what to do to clear the output. 

The following is a brief listing of the common Cmd.exe and UNIX 


commands that you can use inside Windows PowerShell: 


cat dir 

mount rm cd echo move rmdir chdir erase popd sleep clear h ps sort cls 
history pushd tee copy 

kill 

pwd type del 

Ipr 

write 

diff Is 


ren 


If you find yourself using one of these commands reflexively and want 
to learn the real name of the native Windows PowerShell command, 


you can use the Get-Alias command: PS> Get-Alias cls 


CommandType Name Definition 


~---------- ---- ---------- Alias cls Clear- 
Host 

To make examples more readable, the Windows PowerShell User's 
Guide generally avoids using aliases. However, knowing more about 
aliases this early can still be useful if you are working with arbitrary 
snippets of Windows PowerShell code from another source or want to 
define your own aliases. The rest of this section will discuss standard 


aliases and how to define your own aliases. 


Interpreting Standard Aliases 

Unlike the aliases described above, which were designed for name- 
compatibility with other interfaces, the aliases built into Windows 
PowerShell are generally designed for brevity. These shorter names can 
be typed quickly, but are impossible to read if you do not know what 
they refer to. 

Windows PowerShell tries to compromise between clarity and brevity 
by providing a set of standard aliases that are based on shorthand names 
for common verbs and nouns. This allows a core set of aliases for 
common cmdlets that are readable when you know the shorthand 
names. For example, in standard aliases the verb Get is abbreviated to 
g, the verb Set is abbreviated to s, the noun Item is abbreviated to i, the 
noun Location is abbreviated to 1, and the noun Command is abbreviated 
to cm. 

Here is a brief example to illustrate how this works. The standard alias 
for Get-Item comes from combining g for Get and i for Item: gi. The 
standard alias for Set-Item comes from combining s for Set and i for 
Item: si. The standard alias for Get-Location comes from combining g 
for Get and | for Location, gl. The standard alias for Set-Location comes 
from combining s for Set and | for Location, sl. The standard alias for 
Get-Command comes from combining g for Get and cm for Command, 
gcm. There is no Set-Command cmdlet, but if there were, we would be 
able to guess that the standard alias comes from s for Set and cm for 
Command: scm. Furthermore, people familiar with Windows 
PowerShell aliasing who encounter scm would be able to guess that the 
alias refers to Set-Command. 

Creating New Aliases 

You can create your own aliases using the Set-Alias cmdlet. For 
example, the following statements create the standard cmdlet aliases 
discussed in Interpreting Standard Aliases: 

Set-Alias -Name gi - Value Get-Item 


Set-Alias -Name si - Value Set-Item 


Set-Alias -Name gl -Value Get-Location 

Set-Alias -Name sl -Value Set-Location 

Set-Alias -Name gcm -Value Get-Command 

Internally, Windows PowerShell uses commands like these during 
startup, but these aliases are not changeable. If you attempt to actually 
execute one of these commands, you will get an error explaining that 
the alias cannot be modified. For example: 

PS> Set-Alias -Name gi - Value Get-Item 

Set-Alias : Alias is not writeable because alias gi is read-only or 
constant and cannot be written to. 

At line:1 char:10 


+ Set-Alias <<<< -Name gi -Value Get-Item 


Using Tab Expansion 


Command-line shells often provide a way to complete the names of long 
files or commands automatically, speeding up command entry and 
providing hints. Windows PowerShell allows you to fill in file names 


and cmdlet names by pressing the Tab key. 


Note: 
Tab expansion is controlled by the internal function TabExpansion. 
Since this function can be modified or overridden, this discussion is a 


guide to the behavior of the default Windows PowerShell configuration. 


To fill in a filename or path from the available choices automatically, 
type part of the name and press the Tab key. Windows PowerShell will 
automatically expand the name to the first match that it finds. Pressing 
the Tab key repeatedly will cycle through all of the available choices. 
The tab expansion of cmdlet names is slightly different. To use tab 


expansion on a cmdlet name, type the entire first part of the name (the 


verb) and the hyphen that follows it. You can fill in more of the name 
for a partial match. For example, if you type get-co and then press the 
Tab key, Windows PowerShell will automatically expand this to the 
Get-Command cmdlet (notice that it also changes the case of letters to 
their standard form). If you press Tab key again, 

Windows PowerShell replaces this with the only other matching cmdlet 
name, GetContent. 

You can use tab expansion repeatedly on the same line. For example, 
you can use tab expansion on the name of the Get-Content cmdlet by 
entering: 

PS> Get-Con<Tab> 

When you press the Tab key, the command expands to: 

PS> Get-Content 

You can then partially specify the path to the Active Setup log file and 
use tab expansion again: 

PS> Get-Content c:\windows\acts<Tab> 

When you press the Tab key, the command expands to: 


PS> Get-Content C:\windows\actsetup.log 


Note: 

One limitation of the tab expansion process is that tabs are always 
interpreted as attempts to complete a word. If you copy and paste 
command examples into a Windows PowerShell console, make sure 
that the sample does not contain tabs; if it does, the results will be 


unpredictable and will almost certainly not be what you intended. 


Cmdlets are the heart-and-soul of Windows PowerShell, Microsoft's 
new command shell/scripting language. This series provides a task-based 
introduction to Windows PowerShell cmdlets: rather than focusing on the 


individual cmdlets themselves, the emphasis is on the tasks you can carry out 


using those cmdlets. These tasks include everything from reading and writing 


text files to managing event logs to sorting and filtering data. 





1. DATES AND TIMES 


The following articles provide a brief introduction to working with 
dates and times in Windows PowerShell; these tasks include such things as 
retrieving the current date and time, and performing date arithmetic. As is so 
often the case with Windows PowerShell, the code snippets found in these 
articles can either be included within a Windows PowerShell script or typed 
directly into the Windows PowerShell console. 


1.1 Changing a Computer’s Date and Time 


Before explaining how to use the Set-Date cmdlet we should note 
that this is a cmdlet you should use with care. For example, if you’re in an 
Active Directory environment your workstation times must be closely 
synchronized with your domain controller times; if they aren’t, you might 
not be able to log on to the domain. Computer times are often assigned using 
an automatic time service; in that case, you probably don’t need to (and 
probably shouldn’t) set dates and times by hand. However, if you do have a 
need to set dates and times manually then Set-Date provides an easy way to 
do so. 

One way to change the date/time on a computer is to use the -date parameter 
followed by the new date and time. For example, suppose you want to set the 
date and time to 8:30 AM on June 1, 2006. Here’s how you do that: 


“Set-Date -date "6/1/2006 8:30 AM” 


Need to set the clock ahead exactly two days? This command uses the 
Get-Date cmdlet and the AddDays method to advance the clock two days: 


Set-Date ( Get-Date).AddDays (2) 


Other methods that can be used here include AddHours, 
AddMinutes, and AddSeconds. Need to set the clock back | hour due 
to Daylight Saving Time? Then simply set the clock back -1 (minus 1) 
hours, like this: 

Set-Date ( Get-Date).AddHours (-1) 


1.2 Listing Date and Time Information 


As you might expect, the Get-Date cmdlet enables you to 
retrieve the current date and time. As you might also expect, there are a 
few other interesting tricks you can do with Get-Date, some of which 
we’ ll show you momentarily. 

Let’s start with the simplest scenario first. If all you want is the 
current date and time then simply call Get-Date without any additional 
parameters: 


Get-Date 


In return, you’ ll get back something similar to this: 


Wed May 10 10:07:25 2006 


Ah, but suppose you want only the date, not the date and the time? 
Then just use the displayhint parameter and specify date: 


Get-Date -displayhint date 


Or, if you'd prefer just the time: 


Get-Date -displayhint time 
You can also use Get-Date to create a date-time object for any 


date/time. For example, this command creates a variable named $A 
that maps to 12:00 AM on May 1, 2006: 


$A = Get-Date 5 / 1/2006 


What’s that? You need to map $A to 7:00 AM on May 1, 2006? Why 
not: 


$A = Get-Date "5/1/2006 7:00 AM" 


Get-Date also includes a number of methods for doing some handy- 
dandy date arithmetic: 
Add Seconds 


Add Minutes 
Add Hours 
Add Days 

Add Months 
Add Years 


Need to know the date/time 137 minutes from now? This command 
will show you: ( Get-Date).AddMinutes (137) 


1.3 Performing Date Arithmetic 


The New-TimeSpan cmdlet provides a way to do date arithmetic 
within Windows PowerShell. For example, this command tells you the 
number of days between today’s date and New Year’s Eve 2006: 


New-TimeSpan $(Get-Date) $(Get-Date -month 12 -day 31 -year 2006) 


When this command was run on May 10, 2006 we got back the 
following: 


Days p 235 
Hours :0 
Minutes =O 
Seconds 0 


Milliseconds :0 
Ticks —: 203040000000000 
TotalDays t 25 
TotalHours : 5640 
TotalMinutes : 338400 
TotalSeconds —: 20304000 


TotalMilliseconds : 20304000000 


Note. All those who knew that there were 20,304,000,000 milliseconds 
between May 10, 2006 and December 31, 2006 please raise your 
hands. 


To use New-TimeSpan you just need to pass it a pair of date-time 
values. The best way to do that is to use the Get-Date method; that 
helps ensure that you get a pair of date-time objects that New- 
TimeSpan can work with. For our first date, we simply use the Get- 
Date cmdlet without any additional parameters (note that the cmdlet 
must be enclosed in parentheses): 


$(Get-Date) 


For our second date we also call Get-Date, but we tacked on the - 
month, -day, and -year parameters, along with the appropriate values: 


New-TimeSpan $(Get-Date) $(Get-Date -month 12 -day 31 -year 
2006) 

What if you need to know how long it is until a more specific time, 
such as 11:30 PM on December 31st? As usual, no problem: just 
include the -hour and the -minute parameters along with the 
appropriate values (for the hours, use the 24-hour time format). In 
other words: 


New-TimeSpan $(Get-Date) $(Get-Date -month 12 -day 31 -year 2006 -hour 
23 -minute 30) 


2. FILES AND FOLDERS 


The following articles provide a brief introduction to carrying out file 
system management tasks by using Windows PowerShell; these tasks include 
such things as creating, renaming, copying, and deleting files and folders. As 
is so often the case with Windows PowerShell, the code snippets found in 


these articles can either be included within a Windows PowerShell script or 
typed directly into the Windows PowerShell console. 


Want to a copy a file or folder to a new location? Then you want the Copy- 
Item cmdlet. For example, here’s a command that copies the file Test.txt from 
the C:\Scripts folder to the C:\Test folder: 


Copy-Item c:\scripts\test.txt c:\test 


Want to copy all the items in C:\Scripts (including subfolders) to C:\Test? 
Then simply use a wildcard character, like so: 


Copy-Item c:\scripts\* c:\test 


You’re way ahead of us: yes, this next command copies only the .txt files in 
C:\Scripts to C:\Test: 


Copy-Item c:\scripts\*.txt c:\test 


Finally, this command puts a copy of the folder C:\Scripts inside the folder 
C:\Test; in other words, the copied information will be copied to a folder 
named C:\Test\Scripts. Here’s the command: 


Copy-Item c:\scripts c:\test - recurse 


Incidentally, the -recurse parameter is absolutely crucial here; leave it out and 
a Scripts folder will be created in C:\Test, but none of the files and folders in 
C:\Scripts will be copied to the new location; you’ll create a C:\Test\Scripts 
folder, but there won’t be anything in it. Copy-Item Aliases 
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2.1 Creating a New File or Folder 


New-Item is a quick and easy way to create a new file or folder on 
your computer. For example, suppose you want to create a new directory 
named Windows PowerShell within the C:\Scripts folder. To do that call 
New-Item along with: 1) the full path to the new folder; and, 2) the new item 
type (which you can specify using the -type parameter and the value 
directory). The command in question will look like this: 

New-Item c:\scripts\Windows PowerShell -type directory 


To create a new file follow the same procedure, specifying the full path name 
but this time setting the type to file. This command creates the file 
C:\Scripts\New_file.txt: 


New-Item c:\scripts\new_file.txt -type file 


If the item you are trying to create already exists you’ ll get back an error 
message similar to this: 


New-Item : The file 'C:\scripts\new_file.txt' already exists. 


However, you can override the default behavior by including the -force 
parameter: 


New-Item c:\scripts\new_file.txt -type file - force 


If you use -force the existing file New_file.txt will be replaced by the new, 
empty file. 


And speaking of new, empty files, you can also use the -value parameter to 
add some data to your new file. This command adds the phrase This is text 
added to the file at the same time it creates New_file.txt: 


New-Item c:\scripts\new_file.txt -type file -force -value "This is text added 
to the file" 


New-Item Aliases 


2.2 Deleting a File or Folder (Or Other Type of 
Object) 


The Remove-Item cmdlet does exactly what the name implies: it 
enables you to get rid of things once and for all. Tired of the file 
C:\Scripts\Test.txt? Then delete it: 


Remove-Item c:\scripts\test.txt 


You can also use wildcard characters to remove multiple items. For example, 
this command removes all the files in C:\Scripts: 


Remove-Item c:\scripts\* 


There is one catch, however. Suppose C:\Scripts contains subfolders. In that 
case, you’ll be prompted as to whether or not you really do want to delete 
everything in the Scripts folder: 


Confirm 


The item at C:\test\scripts has children and the -recurse parameter was not 
specified. 


If you continue, all children will be removed with the item. Are you 
sure you want to continue? [Y] Yes [A] Yes to All [N] No [L] No 
to All [S] Suspend [?] Help (default is "Y"): 


Is there a way to bypass this prompt? Yep; just tack the -recurse parameter 
onto the end of your command: 


Remove-Item c:\scripts\* - recurse 
Here’s an interesting variation. Suppose the Scripts folder contains a bunch 
of files and you’d like to delete them all. Wait: maybe not all, maybe you’d 
like to leave any .wav files. No problem; just use the -exclude parameter and 
indicate the file types that should be excluded from the deletion: 


Remove-Item c:\scripts\* -exclude *.wav 


What’s that? Now you’d like to remove just .wav and .mp3 files, leaving all 
other file types alone? All you had to do was ask (and use the -include 
parameter): 


Remove-Item c:\scripts\* -include .wav,.mp3 


As you’ve probably figured out, if you use the -include parameter the cmdlet 
will act only on those items specified as part of that parameter. (And, yes, 
you can specify multiple items; just separate items using commas.) By 
contrast, if you use the -exclude parameter those items will be exempt from 
the cmdlet actions. 


And yes, if you want to get really fancy you can use both -include and - 
exclude in the same command. What do you suppose will happen when we 
run this command? 


Remove-Item c:\scripts\* -include *.txt -exclude *test* 


You got it: all the .txt files (as indicated by the -include parameter) in the 
C:\Scripts folder will be deleted, except for any files that have the string 
value test anywhere in the file name (as indicated by the -exclude 
parameter). Try some different variations, and it will soon make perfect 
sense. 


Incidentally, the Remove-Item cmdlet has a -whatif parameter that doesn’t 
actually remove anything but simply tells you what would happen if you did 
call Remove-Item. What do you mean that doesn’t make any sense? Here, 
take a look at this command: 


Remove-Item c:\scripts\*.vbs — whatif 


If we run this command, none of the .vbs files in the folder C:\Scripts will be 
removed; however, we will get back information like this, which lets us 
know which files would be removed if we called Remove-Item without the - 
whatif parameter: 


What if: Performing operation "Remove File" on Target 
"C:\scripts\imapi.vbs". 


What if: Performing operation "Remove File" on Target 
"C:\scripts\imap12.vbs". 


What if: Performing operation "Remove File" on Target 
"C:\scripts\methods.vbs". 


What if: Performing operation "Remove File" on Target "C:\scripts\read- 
write.vbs 


" 


What if: Performing operation "Remove File" on Target "C:\scripts\test.vbs". 


What if: Performing operation "Remove File" on Target 
"C:\scripts\winsat.vbs". 


In addition, you can remove things other than files and folders. For example, 
this command gets rid of an alias named show: 


Remove-lItem alias:\show 


Make a note of how you specify the location: alias:\. That’s standard notation 
for all Windows PowerShell drives: the drive letter followed by a colon 
followed by a \. For example, to switch to the Windows PowerShell drive for 
environment variables use this command: 


Set-Location env:\ 
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rmdir del 


2.3 Moving a File or Folder 


You know how it is: as soon as you have everything set up just 
perfect, you’ll invariably want (or need) to change things. The files you put 
in the C:\Scripts folder? Turns out they should really be in C:\Test. Or 
maybe just the .zip files should be in C:\Test. Or maybe - well, you get the 
idea. Can you use Windows PowerShell to move items from one location or 


another? Let’s put it this way: if you couldn’t, it would be pretty silly to have 
a cmdlet named Move-Item. 


Let’s take a look at a very simple example: moving a single file from one 
folder to another. To do that, call Move-Item followed by, in order, the path 
to the file to be moved and the location to move it to. For example, this 
command moves the file C:\Scripts\Test.zip to C:\Test: 


Move-Item c:\scripts\test.zip c:\test 


Nothing to it, huh? Because Move-Item accepts wildcards you can easily 
move all the .zip files in C:\Scripts to C:\Test: 


Move-Item c:\scripts\*.zip c:\test 


And so on. 


By default, Move-Item will not overwrite any existing files in the target 
folder. For example, suppose you’re trying to move a file named Test.zip 
from C:\Scripts to C:\Test. However, C:\Test already contains a file named 
Test.zip. In that case the move will fail ... unless you include the force 
parameter, which instructs Move-Item to overwrite existing files. This 
command will move Test.zip to the Test folder, even if the file 
C:\Test\Test.zip already exists: 


Move-Item c:\scripts\test.zip c:\test - force 


Also by default, you need to specify only the folder name (e.g., C:\Test) 
when indicating the new location for the item. However, you do have the 
option to specifying a complete path when moving an item, which will 
effectively move the item and then rename it. For example, this command 
moves the file C:\Scripts\950.log to the C:\Test folder. Note, however, the 
actual target location: C:\Test\MyLog.log. That means the command will 
move the file 950.log, and then rename it MyLog.log. 


Here’s what the command looks like: 
Move-Item c:\scripts\950.log c:\test\mylog.log 
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2.4 Renaming a File or Folder 


What can you do with the Rename-Item cmdlet? Well, one thing you 
can do is rename files or folders; all you have to do is call Rename-Item 
followed by two parameters: 


The current path for the file or folder. 
The new name for the file or folder. 


For example, this command renames the file C:\Scripts\Test.txt to 
C:\Scripts\New_Name.txt: 


Rename-Item c:\scripts\test.txt new_name.txt 


Rename-Item Aliases 
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2.5 Replicating (and Extending) the DIR Command 


In its basic form the Get-ChildItem cmdlet provides functionality 
similar to the dir command. For example, if you simply type Get-ChildItem 
at the Windows PowerShell prompt you’ll get back information about the 
objects in the current location: 


Directory: Microsoft.Windows 
PowerShell.Core\FileS ystem::C:\Documents and Settings\kenmyer 


Mode LastWriteTime Length Name 


d---- 3/1/2006 9:03 AM 
Bluetooth Software d---s 
5/10/2006 8:55 AM 


Cookies d---- 5/9/2006 2:09 
PM Desktop d-r-- 

5/9/2006 8:22 AM 

Favorites d-r-- 5/9/2006 2:24 
PM My Documents d-r-- 
3/1/2006 8:15 AM Start 
Menu d---s 3/1/2006 3:41 
PM UserData d---- 
3/16/2006 3:29 PM 

WINDOWS 


That’s all well and good, but you can do a lot more with Get-ChildItem 
than simply list the items found in the current location. For example, in the 
output above you might have noticed that there wasn’t much to look at; 
that’s because the current location happened to be a folder that contained 
only a handful of subfolders. Because of that you might have found it a bit 
more useful if Get-ChildItem had returned not only the names of those 
subfolders but also the contents of those subfolders; that is, you might want a 
list of all the files and folders in the subfolders. No problem; just add the - 
recurse parameter: 


Get-ChildItem - recurse 


Of course, you aren’t limited to working with only the current location; 
in fact, you aren’t limited to working with just files and folders. Would you 
like to see a list of all your environment variables? Then simply pass along 
the path to the environment variable “drive,” like so: 


Get-ChildItem env: 


What about all the registry subkeys found in 
HKEY_ LOCAL MACHINE\SOFTWARE\Microsoft\Windows\CurrentVer 
sion\Uninstall? Why not: 


Get-ChildItem 

HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\Uninstall 

Note. Get-ChildItem cannot be used to retrieve information about the 
registry values contained within a subkey. For that you need to use the Get- 
ItemProperty cmdlet. 


We could do this all day. For example, the -include and -exclude 
parameters make it easy to retrieve a specific set of items from a location. 
Suppose you want information about only the .txt and .log files found in the 
folder C:\Scripts? That’s easy: 


Get-ChildItem c:\scripts\*.* -include *.txt,*.log 


As you can see, we ask for all the files (*.*) found in the folder 
C:\Scripts. We then tack on the -include parameter, specifying two file types: 
* txt and *.log. (And separating the file types using a comma). What do we 
get back? We get back only .txt and log files: 


Mode LastWriteTime Length Name 
-a--- 4/6/2006 8:28PM 3508 950 .Log 
-a--- 5/6/2006 10:06 AM 0 Employees.txt 
-a--- 5/6/2006 10:06 AM 0 Employees_NODUPL.txt 
-a--- 5/6/2006 10:06 AM 0 ExcelData.txt 


-a--- 3/3/2006 9:24 PM 14894 methods.txt 


-a--- 4/28/2006 1:36 PM 41 new_name.txt 


-a--- 3/7/2006 1:44PM 4112 read-write.txt 

-a--- 4/11/2006 11:04 AM 18 servers.txt 

-a--- 5/5/2006 9:09PM 53358 tee.txt 

-a--- 4/26/2006 12:28 PM 1125 temporary_print_file.txt 
-a--- 5/6/2006 10:30PM 34184 test.log 

-a--- 5/9/2006 3:17 PM 58 test.txt 

-a--- 4/6/2006 10:26 PM 205 test_NODUPL.txt 

-a--- 4/28/2006 1:16 PM 27 x.txt 

-a--- 5/8/2006 2:39 PM 25 y.txt 


If we wanted to get back everything except .txt and .log files then we’d 
simply use the exclude parameter instead; this parameter tells Windows 
PowerShell which items should not be included in the returned dataset. 
Here’s what the command looks like: 

Get-ChildItem c:\scripts\*.* -exclude *.txt,*.log 


Give it a try and see what happens. 


The information returned by Get-ChildItem can also be piped into the 
Sort-Object cmdlet, providing a way to sort the data by in some other format. 
Would you rather see files sorted by size (length) than by name? Then use 
this command: 


Get-ChildItem c:\scripts\*.* | Sort-Object length 


Or, if you’d rather see the largest files listed first and the smallest files 


listed last, then add the -descending parameter: 


Get-ChildItem c:\scripts\*.* | Sort-Object length - descending 
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2.6 Retrieving a Specific Item 


The Get-Item cmdlet makes it easy to retrieve a specific item (such as a 
file, a folder, or a registry key). Why would you want to do that? Well, for 
one thing, it makes it very easy to retrieve the properties of those items. For 
example, suppose you’d like to know the last time someone accessed the 
C:\scripts folder. Here’s a command that will retrieve that information: 


$(Get-Item c:\scripts).lastaccesstime 


In essence, we’re using Get-Item to create an object reference to 
C:\Scripts. That’s the reason for the unusual syntax: the command itself - 
Get-Item c:\scripts - is enclosed in parentheses, with a $ pasted on front. The 
property we’re interested in is then tacked on using standard dot notation 
(object.property). Want to know the number of subkeys found in 
HKEY_CURRENT_USER\Software? Here you go: 


$(Get-Item hkcu:\software).subkeycount 


Good question: how did we know that SubkeyCount was a property of 
a registry key? Well, to tell you the truth, we didn’t. But that’s another good 
use for Get-Item: we simply used Get-Item to return an object representing 
HKEY_CURRENT_USER\Software and then piped that object to the Get- 
Member cmdlet: 


Get-Item hkcu:\software | Get-Member 


We then left it up to Get-Member to figure out the properties of the 
registry key. Get-Item Aliases 


gu 


2.7 Verifying the Existence of a File or Folder 


One of the primary uses of Test-Path is to verify the existence of a 
file or folder. For example, this command checks to see whether the file 
C:\Scripts\Test.txt exists: 


Test-Path c:\scripts\test.txt 
Test-Path returns True if the file exists, and returns False if the file does not 
exist. 


As is usually the case with cmdlets, you can use wildcards with Test-Path. 
For example, this script tells you whether or not there are any .wma files in 
C:\Scripts: 


Test-Path c:\scripts\*.wma 


Did someone ask if you can you check for the existence of registry keys 
using Test-Path? Of course you can: 


Test-Path HKCU:\Software\Microsoft\Windows\CurrentVersion 


4. MANAGE FILE PERMISSION 
4.1 Add, and Remove NTFS Permissions 


Managing file and folder permissions in Windows PowerShell is not that easy, and 
there are numerous articles and blog posts describing how it works by using the .NET 
classes. This is far from being comfortable, and there is one major and one minor 
restriction: 


e Path length 
e Generic rights 


This post introduces the NTFSSecurity module, which provides a bunch of cmdlets for 
managing permissions on NTFS drives. It does not use the Windows PowerShell way to 
access the file system, and it works around the MAX_PATH, which is 260 characters 


Windows stores the permissions in the discretionary access control list (DACL), which 
is part of the Security Descriptor. The Security Descriptor also includes the system 





access control list (SACL), where the auditing is configured, and member information. 
This post is about permissions and it does not discuss the SACL or member 
information. 


The DACL contains access control entries (ACEs) that define the permissions someone 
has on the object. Each ACE contains the following values: 


e Account: Who is granted or denied access. Windows does not store the user’s 
SamAccountName, but rather, the SID. 

e Rights: The permissions granted or denied. 

e Type: Grant or deny access. 

e IsInherited: True if the ACE is inherited from a parent object. 

e InheritanceFlags and PropagationFlags: These bits control the inheritance. The 
NTFSSecurity module converts the bits into something more readable that is 
discussed later in this post. 


By default, a security descriptor on the file system inherits permissions from the parent 
object. Users who have full access on drive C also have full access to all subfolders if 
the inheritance is not disabled. 


4.1.1 Reading the permissions of a single item 


The first and easiest task is to retrieve the DACL from a specific file. The 
cmdlet that the NTFSSecurity module provides for retrieving existing 
permissions is Get-NTFSAccess. You can pipe a file or folder to that cmdlet 
or work with the Path parameter: 


Get-Item D:\Data | Get-NTFSAccess 


Get-NTFSAccess -Path D:\Data 


The output might look like this 


PS D:\> Get-Access -Path D:\Data 


Path: D:\Data (Inheritance enabled) 





Account Access Rights Applies to Type IsInherited 
RAANDREE1\randr_@00 FullControl ThisFolderSubfoldersAn... Allow False 
$-1-5-21-3893903987-2340964142-2... FullControl ThisFolderSubfoldersAn... Allow False 
BUILTIN\Administrators FullControl ThisFolderSubfoldersAn... Allow True 
INT AUTHORITY\Authenticated Users Modify, Synchronize ThisFolderSubfoldersAn... Allow True 
INT AUTHORTTY\SYSTEM FullControl ThisFolderSubfoldersAn... Allow True 
BUILTIN\Users ReadAndExecute, Sy... ThisFolderSubfoldersAn... Allow True 


The output is grouped by the file or folder, which is important when getting 
the permissions of more than one object. Next to the path is information 
about if the file or folder inherits the permissions from the parent object. My 
example shows that four of the displayed ACEs have been inherited from 
drive D. 


Some more details about the columns: 


e Account: The account that has been granted or denied access to the 
item. As mentioned, Windows does not store the user’s name, but 
rather, the SID. If the SID can be translated into the name, 
NTFSSecurity shows it; otherwise, the SID is displayed. 

e AccessRights: These are the actual permissions that the account has 
been granted or denied. The list behind this field also supports 
generic rights. 

e Applies to: The .NET Framework stores the inheritance information 
in two-bit fields: InheritanceFlags and PropagationFlags. These fields 
are quite difficult to interpret, so NTFSSecurity converts them into 
something that is known from the Windows Explorer: 

o ThisFolderOnly 
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InheritedFrom 


ThisFolderSubfoldersAndFiles 

ThisFolderAndSubfolders 

ThisFolderAndFiles 

SubfoldersAndFilesOnly 

SubfoldersOnly 

FilesOnly 

e Type: Either Allow or Deny 

e Inherited: If the ACE is inherited from the parent, this is True. The 
first two ACEs have been defined explicitly in the folder. 

e InhertedFrom: This column only contains information if IsInherited 
is True, and it indicates where the ACE is inherited from. 


oOo 0 0 0 O 


4.1.2 Reading the permissions of multiple items 

All NTFSSecurity cmdlets support pipelining. If you need to get the 
permissions from multiple items, you do not need to run a ForEachloop. 
You can simply pipe the files and folders to Get-NTFSAccess. 


dir C:\Data | Get- NTFSAccess 


Get-NTFSAccess provides ways to filter the ACEs. A common scenario is 
to get the ACEs of a specific account or only those that have not been 
inherited. 


If you want to display only permissions that have been added explicitly and 
hide all the inherited permissions, use the ExcludeInheritedswitch: 


dir | Get- NTFSAccess —Excludelnherited 


If you want to display only the permissions assigned to a certain user, use 
the Account parameter: 


dir | Get-NTFSAccess -Account raandree9\randr_000 


Note This displays the permissions as defined in the ACL. This is not the 
effective permissions. Effective permissions will be discussed in an 
upcoming post. 


4.1.3 Granting access 
Granting access to a file or folder is also quite easy to do by using the Add- 
NTFSAccess cmdlet. Add-NTFSAccess provides the following parameters: 


e Account: This can be a user account name (SamAccountName) or a 
SID. The user account name has to contain the domain 
(domain\username). Built-in SIDs are also supported, such as 
Everyone, NT AUTHORITY\SYSTEM, or 


BUILTIN\Administrators. For more information, see Well-known 
security identifiers in Windows operating systems. 

AccessRights: This parameter takes one or more of file system rights, 
for example, FullControl, Modify, or Read. If you want to assign 
multiple rights, provide them in a comma-separated list. 





Note Use Tab expansion or the ISE to get a list of all available 
values. 


AccessType: Allow or deny 

AppliesTo: This parameter sets the scope of the ACE. The options 
are the same as Windows Explorer provides. By default (when not 
defined), the scope is ThisFolderSubfoldersAndFiles. 


Note Use Tab expansion or the ISE to get a list of all available 
values. 


PassThru: By default, the cmdlet does not return any data. If 
the PassThru switch is used, the cmdlet displays the ACL after 
adding the ACE. 


The next commands give the well-known group, Authenticated Users, read 
access to the folder C:\Data. The built-in administrators and the local group, 
Editors, are getting full control: 


Add-NTFSAccess -Path C:\Data ~ 


-Account 'NT AUTHORITY\Authenticated Users’ * 


-AccessRights Read 


Add-NTFSAccess -Path C:\Data ~ 


-Account 'BUILTIN\Administrators', 'raandree9\Editors' * 


-AccessRights FullControl 


4.1.4 Removing access 


Removing access is similar to adding permissions. The command Remove- 
NTFSAccess takes the same parameters as Add-NTFSAccess. 


To remove a user from the ACL, provide the path, the account name, and the 


permissions you want to remove, for example: 


Remove-NTFSAccess D:\Data -Account RAANDREEO\randr_000 -AccessRights 
Read -PassThru 


If the user has different permissions than those you want to remove, nothing 
happens. There needs to be an exact match. 


Note You cannot remove inherited permissions. Get- 
NTFSAccess informs about the source of the inherited permissions 
where the respective ACE can be changed or removed. 


Remove-NTFSAccess accepts pipeline input. If you want to remove all 
permissions for a certain user account, you can read the permissions first and 
then pipe the results to Remove-NTFSAccess. This operation can also run 
reclusively: 


Get-Childltem -Path d:\ -Recurse | 
Get-NTFSAccess -Account raandreeO\randr_000 -Excludelnherited | 
Remove-NTFSAccess 


Note The cmdlets in the NTFSSecurity module do not provide a way to 
process files and folders reclusively. You have to use Get- 

ChildItem or Get-ChildItem2 with the Recurse switch. (The Get- 
ChildItem2 cmdlet is part of the NTFSSecurity module, and it will be 
discussed in a future post.) 


4.2 Manage NTFS Inheritance and Use Privileges 


After you set permissions on a parent folder, new files and subfolders that 
are created in the folder inherit these permissions. If you do not want them to 
inherit permissions, set ApplyTo to “ThisFolderOnly” when you set special 
permissions for the parent folder. In cases where you want to prevent certain 
files or subfolders from inheriting permissions, disable (or block) the 
inheritance. 


There are two types of permissions: 


e Explicit permissions: Set by default when the object is created by 
user action. 

e Inherited permissions: Propagated to an object from a parent object. 
Inherited permissions ease the task of managing permissions and 
ensure consistency of permissions among all objects within a given 
container. 


To add an ACE that does not affect any child elements, use the following 
command: 


Add-NTFSAccess .\Data -Account raandree1\install -AccessRights Modify - 
AppliesTo ThisFolderOnly 


If the AppliesTo parameter is not used, the ACE applies to 
“ThisFolderSubfoldersAndFiles,” like when using the Windows Explorer to add 
permissions. All child elements will inherit the ACE created by the following 
command: 


Add-Access -Path .\Data -Account BUILTIN\Administrators -AccessRights 
FullControl 


To verify which child items have inherited the ACE, you can get and pipe all 
child elements recursively to Get-NTFSAccess. With the following command, 
Windows PowerShell reads only the inherited ACEs that are assigned to the 
built-in administrators group that are inherited from D:\Data: 


dir -Recurse | Get-NTFSAccess -Account BUILTIN\Administrators - 
ExcludeExplicit | Where-Object InheritedFrom -eq 'D:\Data' 





PS D:\> dir -Recurse | Get-NTFSAccess -Account BUILTIN\Administrators -ExcludeExplicit | Where-Object InheritedFrom -eq ‘D:\Data‘ 


Path: D:\Data\Test1 (Inheritance enabled) 


(Account Access Rights Applies to Type IsInherited InheritedFrom 


BUILTIN\Administrators (S-1-5-32... FullControl ThisFolderSubfoldersAn... Allow True D:\Data 


Path: D:\Data\Test.txt (Inheritance enabled) 


(Account Access Rights Applies to Type IsInherited InheritedFrom 


BUILTIN\Administrators (S-1-5-32... FullControl ThisFolderOnly Allow True D:\Data 





4.2.1 Determine inheritance settings 


To determine if a file or folder inherits from its parent, use the Get- 
NTFSAccessInheritance cmdlet (there is also a Get- 
NTFSAuditInheritance cmdlet). There are two ways to specify the file or 
folder: You can use the Path parameter or pipe the file or folder object 

to Get-NTFSAccessInheritance: 


Get-NTFSAccessInheritance -Path C:\Windows 
Get-Item C:\Windows | Get-Inheritance 
The output might look like this: 


C:\> Get-NTFSAccessInheritance -Path C:\Windows 






item InheritanceEnabled FullName None 


: Windows False C:\Windows Windows 
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You can easily get the information for a bunch of items by using the built- 
in Get-ChildItem cmdlet, and then pipe all the items to Get- 
NTFSAccessInheritance: 


Get-Childltem c:\ | Get-NTFSAccessInheritance 


PS C:\> Get-ChildItem c:\ | Get-NTFSAccessInheritance 


Ites InheritanceEnabled FullName 

C: \Debug True C:\Debug 
C:\Documents True C:\Documents 
C:\LongPath True C:\LongPath 
C:\Perflogs False C:\Perflogs 
C:\Program Files False C:\Program Files 
C:\Program Files (x86) False C:\Program Files (x86) 
C:\Users False C:\Users 

c:\vs True C:\VS 

C:\Windows False C:\Windows 

C: \WSManRegKey.reg True C: \WSManRegKey. reg 


4.2.2 Enabling inheritance 


The cmdlet for enabling the inheritance on an object is similar to reading the 
inheritance information: 


Enable-NTFSAccessInheritance -Path .\Data 


By default, the cmdlet does not return any output unless you use 
the PassThru switch. 


The cmdlet provides one additional switch 

parameter: RemoveExplicitAccessRules. When specified, all explicitly 
assigned access control entries (ACEs) will be removed after enabling the 
inheritance. This is like setting the folder back to default permissions. 


PS D:\> Get-NTFSAccess .\Data 


Path: O:\Date (tahenitanceldisabled) 


Account Access Rights Applies to Type 


BUILTIN\Administrators (S-1-5-32... FullControl ThisFolderSubfoldersAn... Allow 
raandreei\Install (S-1-5-21-3893... Modify, Sync... ThisFolderOnly Allow 
RAANDREE1\randr_0@@ (S-1-S-21-38... FullControl ThisFolderSubfoldersAn... Allow 


PS D:\> Enable-NTFSAccessInheritance .\Data -RemoveExplicitAccessRules 


PS D:\> Get-NTFSAccess .\Data 


Path: D:\Data (Inheritance enabled) 


Account Access Rights Applies to Type 


BUILTIN\Administrators (S-1-5-32... FullControl ThisFolderSubfoldersAn... Allow 
NT AUTHORITY \Authenticated Users... Modify, Sync... ThisFolderSubfoldersAn... Allow 
NT AUTHORITY\SYSTEM (S-1-5-18) FullControl ThisFolderSubfoldersAn... Allow 
BUILTIN\Users (S-1-5-32-545) ReadAndExecu... ThisFolderSubfoldersAn... Allow 


The previous output shows that there were only explicitly assigned ACEs in the 
Data folder. These were removed after enabling the inheritance and there are 
only inherited ACEs remaining. 


IsInherited 





Name 

Debug 

Documents 
LongPath 
Perflogs 
Program Files 
Program Files (x86) 
Users 

vs 

Windows 
WSManRegkey. reg 


InheritedFrom 


InheritedFrom 


Note The RemoveExplicitAccessRules switch should be used with care. 
Using this switch by accident can cause users to not be able to access their 
resources. 


A common use case for Enable-NTFSAccessinheritance 


If users can alter the ACL of files or folders, they might remove relevant 
ACEs. The result is that the administrators are no longer able to access the 
data. Another reason why an administrator cannot access data is that 
someone has disabled the inheritance and deleted all inherited ACEs. 


First you need to use the recursive method provided by Get-ChildItem to 
get all files and folders and filter out the items where inheritance is 
enabled.The remaining items are piped to Enable-NTFSAccessInheritance, 
which informs about items where inheritance is enabled with 

the PassThru switch. 


Get-Childltem -Recurse | Get-NTFSAccessInheritance | Where-Object { -not 
$_.InheritanceEnabled } | 
Enable-NTFSAccessInheritance -PassThru 


PS D:\> Get-ChildItem -Recurse | Get-NTFSAccessInheritance | Where-Object { -not $_.InheritanceEnabled } | Enable-NTFSAccessI 
nheritance -PassThru 


Item InheritanceEnabled FullName Name 
0:\GPO True D:\GPO GPO 
0: \Data\Test2 True D:\Data\Test2 Test2 


4.2.3 Disabling inheritance 


In NTFSSecurity, you also need to disable inheritance. When enabling inheritance 
you have to determine what to do with explicit ACES (usually you keep them). When 
disabling inheritance, the inherited ACEs can be converted into explicit ones or they 
can be removed. This is controlled by the RemovelnheritedAccessRules switch. 


In the following example, the inheritance for the folder GPO is enabled. The folder is 
inheriting four ACEs from the parent (drive D). After disabling inheritance, the ACEs 
still exist as explicit ACEs. 
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PS D:\> Get-NTFSAccess .\GPO 


Path: D:\GPO (Inheritance enabled) 


Account 

BUILTIN\Administrators (S-1-5-32... 
NT AUTHORITY \Authenticated Users... 
NT AUTHORITY\SYSTEM (S-1-5-18) 
BUILTIN\Users (S-1-5-32-545) 


PS D:\> Disable-Inheritance .\GPO 
PS D:\> Get-NTFSAccess .\GPO 


Access Rights 


FullControl 


Modify, Sync... 


FullControl 


ReadAndExecu... 


Path: D:\6PO (Inhenttancer disabled)! 


Account 

NT AUTHORITY\Authenticated Users... 
NT AUTHORITY\SYSTEM (S-1-5-18) 
BUILTIN\Administrators (S-1-5-32... 
BUILTIN\Users (S-1-5-32-545) 


Note When using the RemoveInheritedAccessRules switch, you need 
to make sure that the access is guaranteed after disabling the 
inheritance. If an item does not have explicit ACEs assigned and you 


Access Rights 


Modify, Sync... 


FullControl 
FullControl 


ReadAndExecu... 


Applies to 


ThisFolderSubfoldersAn... 
ThisFolderSubfoldersAn. .. 
ThisFolderSubfoldersAn... 
ThisFolderSubfoldersAn... 


Applies to 


ThisFolderSubfoldersAn... 
ThisFolderSubfoldersAn... 
ThisFolderSubfoldersAn... 
ThisFolderSubfoldersAn... 


Type 

Allow 
Allow 
Allow 
Allow 


Type 

Allow 
Allow 
Allow 
Allow 


remove all inherited ACEs, nobody will be able to access the file. 


However, an administrator can always use the back-up privilege or take 


ownership to get access again. 


4.2.4 Using privileges 


Note There was a big change in Windows 8 and Windows Server 2012 
regarding how privileges can be used. The features described in this 
section work only on Windows 8.1, Windows 8, Windows 


Server 2012 R2, and Windows Server 2012. 


Sometimes permissions are hosed and access is denied, even if you are the 
mighty administrator. In this case, you cannot even read the existing ACL. 
Of course, the administrator can always take the ownership of an object, but 
this erases the existing ACL of the object. This is bad because you cannot 


determine by the ACL the people who need to have access. 


Windows has a very handy concept of privileges. A privilege represents the 
right of an account, such as a user or group account, to perform various 
system-related operations on the local computer, such as shutting down the 
system, loading device drivers, or changing the system time. Privileges differ 


from access rights in two ways: 


e Privileges control access to system resources and system-related 
tasks, whereas access rights control access to securable objects. 

e Asystem administrator assigns privileges to user and group accounts, 
whereas the system grants or denies access to a securable object 
based on the access rights granted in the ACEs in the object's DACL. 





InheritedFrom 


InheritedFrom 


When dealing with files and folders, three privileges are worth looking at: 


e Back up files and directories: 
This user right determines which users can bypass file and directory, 
registry, and other persistent object permissions for the purposes of 
backing up the system. By default, Administrators and Backup 
Operators can make use of this privilege. 

e Restore files and directories: 
This security setting determines which users can bypass file, 
directory, registry, and other persistent objects permissions when 
restoring backed up files and directories, and it determines which 
users can set valid security principals as the owner of an object. 


Specifically, this user right is similar to granting the following 
permissions to the user or group in question on all files and folders 
on the system: 


o Traverse Folder/Execute File 
o Write 


By default Administrators and Backup Operators have this privilege 
assigned. 


e Take ownership of files or other objects: 
This security setting determines which users can take ownership of 
any securable object in the system, including Active Directory 
objects, files and folders, printers, registry keys, processes, and 
threads. By default, this privilege is assigned to Administrators. 


For a list of privileges, refer to Privileges in the TechNet Library. 


To create the situation described previously, you can use the following 
command sequence: 


Set-NTFSOwner .\Data -Account 'NT AUTHORITY\SYSTEM' 
Disable-NTFSAccessInheritance .\Data -RemovelnheritedAccessRules 


The first command assigns the ownership of the Data folder to the SYSTEM 
account, and the second command disables the inheritance. Now only the 
SYSTEM account can access the item. 


S D:\> Get-NTFSAccess .\Data 
et-NTFSAccess : Access is denied. (Exception from HRESULT: 0x8@070005 (E_ACCESSDENIED)): [\\?\0:\Data] 
it line:1 char:1 
Get-NTFSAccess .\Data 
+ CategoryInfo : OpenError: (.\Data:String) [Get-NTFSAccess], UnauthorizedAccessException 
+ FullyQualifiedErrorId : ReadError,NTFSSecurity.GetAccess 


Windows Explorer is not helpful either: 


58 


D:\Data 
Owner Unable to display current owner, Chonge 


| Permissions | Auditing | Effective Access 


@ You do not have permission to view this object's security properties, even as an administrative user. — 


To try taking ownership of the object, which includes permission to view its properties, click Change above. 





4.2.5 Enabling privileges 


The NTFSSecurity module provides the Enable-Privileges cmdlet. This 
cmdlet enables the privileges Backup, Restore, and Security (if you have 
them). You can get a list of available privileges by using Get-Privilege. 


Running Get-Privilege in a non-elevated Windows PowerShell console 
should return something like this: 





C:\> Get-Privileges 


Privilege PrivilegeAttributes PrivilegeState 
Shutdown Enabled Enabled 
ChangeNotify EnabledByDefault, Enabled Enabled 
Undock Disabled Disabled 
IncreaseWorkingSet Disabled Disabled 
TimeZone Disabled Disabled 


The privileges Backup, Restore, and Security are missing. If you run the 
same command in an elevated Windows PowerShell console, the list gets 
much longer: 


C:\> Get-Privileges 





Privilege PrivilegeAttributes 








Disabled 

SystemProfile Disabled 
SystemTime Disabled 
ProfileSingleProcess Disabled 
IncreaseBasePriority Disabled 
cen tac Disabled 
Shutdown Disabled 

Debug Enabled 
SystemEnvironment Disabled 
ChangeNotify EnabledByDefault, Enabled 
RemoteShutdown Disabled 
Undock Disabled 

ManageVolume Disabled 
Impersonate EnabledByDefault, Enabled 
CreateGlobal EnabledByDefault, Enabled 
IncreaseWorkingSet Disabled 
TimeZone Disabled 
CreateSymbolicLink Disabled 


All these privileges are disabled by default. Having them enabled all the time 
would be quite dangerous and would increase ones scope of action too much. 
However in some scenarios, it is required to make use of privileges, for example, 
when doing backup jobs, data migrations, or permission cleanups. 


To enable the privileges, call Enable-Privileges. You will get a warning message 
that informs you about the enabled privileges. 


Note If you call the cmdlet in a non-elevated Windows PowerShell 
console, and hence, you do not hold the proper privileges, the following 
error message returns: 

Enable-Privileges: Could not enable requested privileges. Cmdlets of 
NTFSSecurity will only work on resources you have access to. 


After calling Enable-Privileges, you can check the state of the privileges by 
using Get-Privileges. 


Using enabled privileges 


Enabling the privileges is pretty much all you need to do. The process that 
has enabled them uses them automatically. 


After removing the permissions from the Data folder, there is no way to 
access it or display the owner or ACL. However, after enabling the 
privileges, Windows bypasses the ACL and grants you full access (thanks to 
the Backup and Restore privilege). 
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PrivilegeState 


Disabled 





Disabled 
Disabled 
Disabled 
Disabled 
Disabled 
Disabled 





Disabled 
Enabled 
Disabled 
Enabled 
Disabled 
Disabled 
Disabled 
Enabled 
Enabled 
Disabled 
Disabled 
Disabled 





D:\> Enable-Privileges 





nd folders. Use Disable-Privileges to disable them and Get-Privileges for an overview. 
D:\> Get-NTFSOwner .\Data 


:\Data NT AUTHORITY\SYSTEM 


D:\> Get-NTFSAccess .\Data 


Get-NTFSAccess does not return any data because there is no ACE in the 
ACL. Remember that all ACEs have been removed by disabling the 
inheritance. 


Now you can take the ownership and enable inheritance again: 
Set-NTFSOwner -Path .\Data -Account BUILTIN\Administrators 
Enable-NTFSInheritance -Path .\Data 


D:\> Set-NTFSOwner -Path .\Data -Account BUILTIN\Administrators 
O:\> Enable-Inheritance -Path .\Data 

0:\> 

O:\> Get-NTFSOwner .\Data 


\Item Owner 


D:\Data BUILTIN\Administrators 
PS D:\> Get-NTFSAccess .\Data 


Path: D:\Data (Inheritance enabled) 





Account Access Rights Applies to Type IsInherited 
ILTIN\Administrators FullControl ThisFolderSubfoldersAn... Allow True 
T AUTHORITY \Authenticated Users Modify, Sync... ThisFolderSubfoldersAn... Allow True 
T AUTHORITY\SYSTEM FullControl ThisFolderSubfoldersAn... Allow True 
ILTIN\Users ReadAndExecu... ThisFolderSubfoldersAn... Allow True 


Now the access is how it should be again. 


4.2.6 Disabling privileges 


If you no longer need the privileges, it is strongly recommended to disable 
them. Use the command Disable-Privileges for this. 


After calling Disable-Privileges, you can check the state of the privileges by 
using Get-Privileges. 


5. MANAGE SERVICES 


There are eight core Service cmdlets, designed for a wide range of service 
tasks . We will look only at listing and changing running state for services, 
but you can get a list Service cmdlets by using Get-Help &#42;-Service, 


NING: The privileges ‘Backup’, ‘Restore’, ‘TakeOwnership’ and ‘Security’ are now enabled giving you access to all files 


InheritedFrom 


and you can find information about each Service cmdlet by using Get-Help, 
such as Get-Help New-Service.+ 


5.1 Getting Services 


You can get the services on a local or remote computer by using the Get- 
Service cmdlet. As with Get-Process, using the Get-Service command 
without parameters returns all services. You can filter by name, even using 
an asterisk as a wildcard: 


PS> Get-Service -Name se* 
Status Name DisplayName 


Running seclogon 
Running SENS 
Stopped ServiceLayer 


Secondary Logon 
System Event Notification 
ServiceLayer 


Because it is not always obvious what the real name for the service is, you 
may find you need to find services by display name. You can do this by 
specific name, using wildcards, or using a list of display names: 


PS> Get-Service -DisplayName se* 
Status Name DisplayName 


Running lanmanserver Server 


Running SamSs Security Accounts Manager 
Running seclogon 
Stopped ServiceLayer ServiceLayer 

Running wscsvc Security Center 


PS> Get-Service -DisplayName ServiceLayer, Server 


Secondary Logon 


Status Name DisplayName 
Running lanmanserver Server 
Stopped ServiceLayer ServiceLayer 


You can use the ComputerName parameter of the Get-Service cmdlet to get 
the services on remote computers. The ComputerName parameter accepts 
multiple values and wildcard characters, so you can get the services on 
multiple computers with a single command. For example, the following 
command gets the services on the Server01 remote computer. 


Get-Service -ComputerName Server@1 


5.2 Getting Required and Dependent Services 


The Get-Service cmdlet has two parameters that are very useful in service 
administration. The DependentServices parameter gets services that depend 
on the service. The RequiredServices parameter gets services upon which 
this service depends. 


These parameters just display the values of the DependentServices and 
ServicesDependedOn (alias=RequiredServices) properties of the 
System.ServiceProcess.ServiceController object that Get-Service returns, but 
they simplify commands and make getting this information much simpler. 


The following command gets the services that the Lanman Workstation 
service requires. 


PS> Get-Service -Name LanmanWorkstation -RequiredServices 


Status Name DisplayName 

Running MRxSmb2@ SMB 2.@ MiniRedirector 

Running bowser Bowser 

Running MRxSmb1@ SMB 1.x MiniRedirector 

Running NSTI Network Store Interface Service 


The following command gets the services that require the 
LanmanWorkstation service. 


PS> Get-Service -Name LanmanWorkstation -DependentServices 


Status Name DisplayName 

Running SessionEnv Terminal Services Configuration 
Running Netlogon Netlogon 

Stopped Browser Computer Browser 

Running BITS Background Intelligent Transfer Ser... 


You can even get all services that have dependencies. The following 
command does just that, and then it uses the Format-Table cmdlet to display 
the Status, Name, RequiredServices and DependentServices properties of the 
services on the computer. 


Get-Service -Name * | where {$_.RequiredServices -or 
$¢_.DependentServices} | Format-Table -Property Status, Name, 
RequiredServices, DependentServices -auto 


5.3 Stopping, Starting, Suspending, and Restarting 
Services 


The Service cmdlets all have the same general form. Services can be 
specified by common name or display name, and take lists and wildcards as 
values. To stop the print spooler, use: 


Stop-Service -Name spooler 


To start the print spooler after it is stopped, use: 


Start-Service -Name spooler 


To suspend the print spooler, use: 


Suspend-Service -Name spooler 


The Restart-Service cmdlet works in the same manner as the other Service 
cmdlets, but we will show some more complex examples for it. In the 
simplest use, you specify the name of the service: 


PS> Restart-Service -Name spooler 

WARNING: Waiting for service 'Print Spooler (Spooler)' to finish 
starting... 

WARNING: Waiting for service 'Print Spooler (Spooler)' to finish 
starting... 

PS> 


You will notice that you get a repeated warning message about the Print 
Spooler starting up. When you perform a service operation that takes some 
time, Windows PowerShell will notify you that it is still attempting to 
perform the task. 


If you want to restart multiple services, you can get a list of services, filter 
them, and then perform the restart: 


PS> Get-Service | Where-Object -FilterScript {$_.CanStop} | 
Restart-Service 
WARNING: Waiting for service ‘Computer Browser (Browser)' to finish 
stopping... 
WARNING: Waiting for service ‘Computer Browser (Browser)' to finish 
stopping... 

Restart-Service : Cannot stop service ‘Logical Disk Manager 
(dmserver)' because 

it has dependent services. It can only be stopped if the Force 
flag is set. 
At line:1 char:57 

+ Get-Service | Where-Object -FilterScript {$_.CanStop} | Restart- 
Service <<<< 
WARNING: Waiting for service 'Print Spooler (Spooler)' to finish 
starting... 
WARNING: Waiting for service 'Print Spooler (Spooler)' to finish 
starting... 


These Service cmdlets do not have a ComputerName parameter, but you can 
run them on a remote computer by using the Invoke-Command cmdlet. For 
example, the following command restarts the Spooler service on the 
Server01 remote computer. 


Invoke-Command -ComputerName Server@1 {Restart-Service Spooler} 


5.4 Setting Service Properties 


The Set-Service cmdlet changes the properties of a service on a local or 
remote computer. Because the service status is a property, you can use this 
cmdlet to start, stop, and suspend a service. The Set-Service cmdlet also has 
a StartupType parameter that lets you change the service startup type. 


To use Set-Service on Windows Vista and later versions of Windows, open 
Windows PowerShell with the "Run as administrator" option. 


11. MANAGE WINDOWS ROLES AND 
FEATURES 


In Windows Server 2012 a server role represents an installable unit of 
functionality that defines the primary function of a server. For instance, you 


may install Active Directory Domain Services (AD DS) to create a dedicated 
domain controller for your forest. 


To find out which PowerShell models are loaded or available, simply run: 


get-module 





get-module -listAvailable 





as shown here: 
PS C:\windows\system32> Get-Module 


ModuleType Version Name Exportedcommands 


.0.0. ISE {Get-IseSnippet, Import-IseSnippet, | 
Manifest .1.0. Microsoft. PowerShel] .Management {Add-computer, Add-content, Checkpoi 
Manifest -1.0. Microsoft. PowerShel].utility {Add-Member, Add-Type, Clear-Variable 


PS C:\windows\system32> Get-Module -ListAvailable 
Directory: C:\windows\system32\windowsPowerShel1\v1.0\mModules 


ModuleType Version Name Exportedcommands 

Manifest AppLocker {Get-AppLockerFileInformation, Get-Ag 
Manifest Appx {Add-AppxPackage, Get-AppxPackage, Ge 
Manifest BestPractices {Get-BpaModel, Get-BpaResult, Invoke 
Manifest BitLocker {unlock-BitLocker, Suspend-BitLocker | 
Manifest BitsTransfer {Add-BitsFile, Complete-BitsTransfer | 
Manifest Branchcache {add-BcDataCacheExtension, Clear-sBCCa 
Manifest Cimcmdlets {Get-CimAssociatediInstance, Get-Cimc] 
Manifest Deduplication {Disable-Dedupvolume, Enable-Dedupvol] 
URE h DirectAccessClientComponents {Disable-DAManualEntryPointSelection, 
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If Server Manager PowerShell module is not already installed, it can be 
imported with 
import-module ServerManager -passthru 


PS C:\windows\system32> Import-Module ServerManager -PassThru 
ModuleType Version Name Exportedcommands 


2.0.0.0 serverManager {Get-windowsFeature, Install-w... 


PS C:\windows\system32> Get-Module 


ModuleType Version Name ExportedCcommands 


Script .0.0. ISE {Get-IseSnippet, Import-IseSni... 
Manifest ea AUP Microsoft. PowerShell] .Management {Add-Computer, Add-Content, Ch... 
Manifest .1.0. Microsoft. PowerShel].uti lity {Add-Member, Add-Type, Clear-v... 
Script .0. ServerManager {Get-windowsFeature, Install-w.. 


PS C:\windows\system32> 





Use get-commanato list out and there are three cmdlets in ServerManager 
module as shown below.. 


PS C:\Users\Administrator> Get-Command -Module servermanager 


CommandType Name 

Add-wWindows Feature 

Remove-Windows Feature 
Function Disable-ServerManagerStandardUserRemoting 
Function Enable-ServerManagerStandarduUserRemoting 
Cmdlet Get-windows Feature 
Cmdlet Install-windowsFeature 
Cmdlet Uninstal1-windowsFeature 


PS C:\Users\Administrator> 


Notice that Install-WindowsFeature and Uninstall- 
WindowsFeature replace Add-WindowsFeature and Remove- 





Modu leName 


ServerManager 
ServerManager 
ServerManager 
ServerManager 
ServerManager 
ServerManager 
ServerManager 





WindowsFeature, respectively. The latter two cmdlets were used to install 


features in Windows Server 2008 R2 and are now as aliases. 


11.1 Identify Current State 


The first thing to do is to always use Get-WindowsFeature to find out what 
roles and features are available and the current state of the machine. The 
output also reveals the precise Feature Names to use with Server Manager 


PowerShell cmdlets as shown below. 


PS C:\windows\system32> Get-windowsFeature 


Display Name Name Install state 


{ ] Active Directory Certificate Services AD-Certificate 
{ ] certification Authority ADCS-Cert-Authority 
{ ] certificate Enrollment Policy web Service ADCS-Enrol]-web-Pol 
{ ] Certificate Enrollment web Service ADCS-Enrol1-web-Svc 
{ ] Certification Authority web Enrollment ADCS-web-Enrol Iment 
{ ] Network Device Enrollment Service ADCS-Device-Enrol Iment 
{ ] Online Responder ADCS-Online-Cert 
Active Directory Domain Services AD-Domain-Services 
Active Directory Federation Services ADFS-Federation 
Active Directory Lightweight Directory Services ADLDS 
Active Directory Rights Management Services ADRMS 
{ ] Active Directory Rights Management Server ADRMS-Server 
{ ] Identity Federation Support ADRMS-Identity 
Application Server Application-Server 
(xX) .NET Framework 4.5 AS-NET-Framework 

COM+ Network Access AS-Ent-Services 





Available 
Avai lable 
Available 
Avai lable 
Available 
Available 
Available 
Available 
Available 
Available 
Avai lable 
Avai lable 
Avail lable 
Installed 
Installed 
Available 


Display Name shows what we see in Server Manager graphical UI when 
adding or removing roles and features. The actual class or object names are 
listed under Name. The object name is what to use with Server Manager 
cmdlets. A checkmark preceding a display name means that the role or feature 
is currently installed as indicated by what is shown in the Install State column 


as well. 


11.2 Installing a Role or Feature 


We use the Add-WindowsFeature cmdlet to install both server roles and 
features. To leverage this cmdlet, we simply pass a comma-separated list of 
either display names (in quotes) or short names for the roles and/or features 


you wish to install. 


PS>Add-WindowsFeature role, feature, etc. 


See the following exhibit for an interface example in which we install the File 
Server, Domain Name System (DNS), and Dynamic Host Configuration 
Protocol (DHCP) server roles on a Windows Server 2012 R2 server. 





"Y Adminéstrator: Command Prompt - powershell 


Success {DNS Server, DHCP Server, File Server} 





To verify that the new server roles have been installed successfully, let’s fire 
up Server Manager and have a look at the Roles tree: 
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is 


a 
© ~ Server Manager * Dashboard ~@ 1 FP ‘Manage! Toots View Help 


| Remove Roles and Features 


TH Dashboard WELCOME TO SERVER MANAGER 


Add Servers 


Local Server | | Create Server Group 


ey Configure this local ser\__|Sener Manager Properties 








Hii All Servers 
fll ADDS 
fa DNS QUICK START 


iif File and Storage Services > 2 Add roles and features 


Add other servers to manage 


4 Create a server group 








ROLES AND SERVER GROUPS 


Roles:3 | Server groups: 1 | Servers total: 1 


igi AD Ds 1 & DNs 


® Manageability ® Manageability 
Events Events 
Services Services 
Performance Performance 


BPA results BPA results 





Verifying server role installation 
Ah, success! 


11.3 Removing a Role or Feature 


Removing Windows Server 2012 roles and features by using PowerShell is an 
equally simple procedure. To do this, we invoke the Remove- 
WindowsFeature cmdlet. You can throw in the optional —restart parameter 
to specify an automatic server restart if Windows needs to do so. 


7). Administrator: Command Prompt - powershell 








One word of warning: If you do elect to add the -restart parameter to your 
cmdlet, the server will restart (if necessary) with absolutely no timeout or 
other warning. 
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